<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">

  <head>
    <title>Migrating to Postmodern 1.10</title>
    <link rel="stylesheet" type="text/css" href="style.css"/>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
  </head>

  <body>

    <h1>Migrating to Postmodern 1.10</h1>

    <p>A number of backwards-incompatible changes are introduced in
    this version of the library &#x2015; there are a few small
    cleanups, and the database-access object system has been
    completely overhauled.</p>

    <h2><code>with-connection</code></h2>

    <p>The old <code>with-connection</code> form has been replaced by
    what used to be called <a
    href="postmodern.html#with-connection"><code>with-connection*</code></a>.
    This means that if you had code like this...</p>

    <pre class="code">
(with-connection ("my-db" "harry" "****" "localhost") ...)</pre>

    <p>... you should change it to ...</p>

    <pre class="code">
(with-connection (list "my-db" "harry" "****" "localhost") ...)</pre>

    <p>... since the whole list is now evaluated. Similarly, if you
    were using <code>with-connection*</code>, you should remove the
    asterisk.</p>

    <h2>Integrating custom data types</h2>

    <p>CL-postgres now exports <a href="cl-postgres.html#reading">ways
    to manipulate</a> the way it reads values from query results. The
    old <code>s-sql:sql-ize</code> generic has been moved to
    <code>cl-posgres:<a
    href="cl-postgres.html#to-sql-string">to-sql-string</a></code>,
    and can be used to control the way values are written out when
    passed as arguments to prepared statements or inserted in <a
    href="s-sql.html">S-SQL</a> query forms.</p>

    <p><a href="simple-date.html"><code>simple-date</code></a> is no
    longer depended on by CL-postgres and S-SQL, but uses the above
    interface to integrate itself. Load it <em>after</em> loading
    CL-postgres, and suitable readers and writers for its types will
    be registered. Integrating other date/time libraries is
    trivial.</p>

    <h2>Errors and reconnecting</h2>

    <p>In previous versions, only the
    <code>database-connection-lost</code> conditions offered a
    <code>:reconnect</code> restart. There are now various conditions
    offering this restart, all subtypes of <a
    href="cl-postgres.html#database-connection-error"><code>database-connection-error</code></a>,
    and the library tries its very best to wrap all hard-to-prevent
    errors with such a restart (socket errors, database shutdowns).
    The goal is that you can use this feature to cleanly and simply
    add functionality for recovering from connectivity problems and
    server restarts. If you still have issues here, please discuss
    them on the mailing list (universal error recovery is rather hard
    to test).</p>

    <p>There is now also a large set of condition types exported from
    the <code>cl-postgres-error</code> package, which can make writing
    <code>handler-case</code> forms around database code a lot more
    pleasant. See <code>cl-postgres/error.lisp</code> for the list (or
    just cause the error you are interested in to be raised, and look
    at its type).</p>

    <h2>The DAO system</h2>

    <p>This is where upgrading might be somewhat painful. The old
    <code>deftable</code> macro has been dropped completely, in favour
    of the <a
    href="postmodern.html#dao-class"><code>dao-class</code></a>
    metaclass. The focus of this part of the library has shifted from
    defining <em>tables</em> to defining <em>access objects</em>. You
    can still generate simple CREATE TABLE statements using the <a
    href="postmodern.html#dao-table-definition"><code>dao-table-definition</code></a>
    function, but this is intended to just be a shortcut. Table
    definition is now the responsibility of the library user, not the
    library.</p>

    <p>So why this regression in functionality? It turned out that
    coupling access objects and table definitions like this was not
    such a good idea. You might want to create access objects for
    views, or for tables with all kinds of complicated constraints.
    Adding support for this to <code>deftable</code> would have turned
    it into an even bigger behemoth than it already was, and not
    fundamentally solve the problem.</p>

    <p>So now we have a nice, clean DAO interface, and no
    schema-definition interface at all (<code>create-template</code>
    and friends were also dropped). The most notable change is
    probably that the <code>:auto-id</code> option is gone. This was
    very convenient but horribly 'magical'. If you had something like
    this:</p>

    <pre class="code">
(deftable product ()
  ((name :type string :initarg :name :accessor product-name)
   (weight :type float :initarg :weight :accessor product-weight))
  (:class-name product)
  (:auto-id t)
  (:indices (:unique name)))

(defun create-tables ()
  ; ...
  (create-table 'product))</pre>

    <p>The equivalent could look like this:</p>

    <pre class="code">
(defclass product ()
  ((id :col-type serial :initarg :id :accessor product-id)
   (name :col-type string :initarg :name :accessor product-name)
   (weight :col-type float :initarg :weight :accessor product-weight))
  (:keys id)
  (:metaclass dao-class))

(defun create-tables ()
  ; ...
  (execute (dao-table-definition 'product))
  (execute (:create-unique-index 'product-name :on 'product :fields 'name)))</pre>

   <p>Or you could explicitly create the id sequence and give the
   <code>id</code> field a <code>:col-default</code> of
   <code>(:nextval "product_ids")</code>, to have more control over
   the id generation.</p>

   <p>The above example should give you a basic idea of the new
   interface: DAO classes are now created by regular class
   definitions. Instead of <code>:type</code> options, column slots
   should get <code>:column</code> or <code>:col-type</code> options.
   The semantics of creating and inserting DAOs have been slightly
   adjusted: There is no magic happening when you create a DAO
   instance (it used to fetch id values), except when you give
   <code>make-instance</code> a <code>:fetch-defaults</code> keyword
   argument, in which case it will query the database for the rows'
   default values, and put them in the instance. Usually, it is
   cleaner to not use this, since it generates extra queries and does
   not work for stuff like <code>serial</code> fields anyway, where no
   proper <code>:col-default</code> can be given. When an object is
   inserted into the database with <a
   href="postmodern.html#insert-dao"><code>insert-dao</code></a>, some
   slots may be unbound. These will then, both in the database and in
   the object, be assigned values based on the column defaults. For
   example, if you have the above <code>product</code> class:</p>

   <pre class="code">
(defvar *p* (make-instance 'product :name "brick" :weight 2))
;; The id slot is unbound
(insert-dao *p*)
(print (product-id *p*))
;; Here it will have received a new id value</pre>

    <p>Note that this works even for <code>serial</code> types, since
    the defaults are fetched by giving the INSERT statement a
    RETURNING clause, so the association between default values and
    columns is handled by the database, not the DAO class.</p>

  </body>
</html>
